home *** CD-ROM | disk | FTP | other *** search
/ PsL Monthly 1993 December / PSL Monthly Shareware CD-ROM (December 1993).iso / prgmming / dos / pascal / mouse.exe / MOUSE.DOC < prev    next >
Text File  |  1989-06-03  |  56KB  |  1,357 lines
  1.                            MOUSE V3.1
  2.                         as of 28 May 1989
  3.                        Author: Michael Day
  4.  
  5.    This program is released to the public domain by the author.
  6.  
  7.  
  8.  
  9.  
  10.      Mouse  has gone through a number of major rewrites since  it
  11. was originally introduced. This latest release has changed the way
  12. some  of the functions work. If you are using the  old  mouse
  13. program, you will most likely have to make some minor changes  to
  14. your program to use this new version of Mouse.
  15.  
  16.      The most significant difference is how the mouse positioning
  17. is  being  handled now. In the earlier Mouse program  there  were
  18. separate  routines for the text and graphics  mouse  positioning,
  19. and  separate variables. This is no longer the case.  The  double
  20. routines  have  been merged into single routines with a  flag  to
  21. (TextMouse) control whether the position data is treated as  text
  22. positioning or graphics positioning. Further, new functions  have
  23. been  added to convert the virtual position information  provided
  24. by the mouse back to real screen positioning needed by programs.
  25.  
  26.      To properly set the mouse position, or read the position  of
  27. the  mouse,  you  should now use  the  translation  functions  to
  28. correctly  derive  the proper mouse position on the  screen.  The
  29. advantage   to  this  is  that  the  translation   routines   are
  30. intelligent enough to be able to properly convert the positioning
  31. information  based  on  the current display type  and  mode.  The
  32. standard CGA, EGA, VGA, and Hercules displays and their modes are
  33. supported.  Note: most mouse drivers do not support  extended  or
  34. non-standard  display modes. You may need to override  the  mouse
  35. position translator with your own if you use a non-standard mode.
  36.  
  37.      The other big change is the addition of the simulated  mouse
  38. cursor.  Why a simulated mouse cursor? Two reasons, one,  if  you
  39. don't  have  a mouse, you can still make believe that you  do  by
  40. using  the simulated cursor and keyboard input. And two, it  gets
  41. around a problem with Turbo Pascal in that it is not well behaved
  42. when  it comes to mice. Turbo Pascal and the Turbo Debugger  will
  43. trash  the mouse cursor when using the standard mouse  driver  to
  44. generate  the  cursor.  You  can get around  this  by  using  the
  45. simulated  cursor  instead. Since it operates  via  the  program,
  46. Turbo  Pascal  and  Turbo  Debugger  are  happy.  There  is   one
  47. disadvantage  though, if the simulated mouse is used  the  cursor
  48. operation  will be slow and jerky. I recommend that you  continue
  49. to   use  the  driver  generated  mouse  cursor  for   commercial
  50. applications  where  possible. The simulated mouse is  mainly  to
  51. allow  you to use a mouse while debugging a program or to  run  a
  52. program without a mouse at all.
  53.  
  54.  
  55.  
  56. ISR Support:
  57.  
  58.      Another  addition is ISR support for the mouse so  that  you
  59. don't have to sprinkle ReadMouse calls through out your  program.
  60. This can make mouse programming much simpler.
  61.  
  62.  
  63.  
  64. Graphic Mouse Cursor:
  65.  
  66.      There are 19 supplied Graphic mouse cursors in the  program.
  67. You   can   select   the   desired   cursor   by   calling    the
  68. MouseGraphicCursor function which will cause the selected  cursor
  69. to  be loaded from the table. You can see which cursor  has  been
  70. loaded  by  looking  at  the  global  MouseGStyle  variable.   If
  71. MouseGStyle contains a -1 it means that a custom cursor has  been
  72. loaded.  You  can load your own custom graphic  mouse  cursor  by
  73. using the SetMouseGraphicCursor function.
  74.  
  75.  
  76.  
  77. Text Mouse Cursor:
  78.  
  79.      There are 16 supplied Text mouse cursors in the program. You
  80. can  select  the desired cursor by  calling  the  MouseTextCursor
  81. function  which will cause the selected cursor to be loaded  from
  82. the table. You can see which cursor has been loaded by looking at
  83. the global MouseTStyle variable. If MouseTStyle contains a -1  it
  84. means  that  a  custom cursor has  been  loaded.  If  MouseTStyle
  85. contains  a 0, then the current hardware cursor is used. You  can
  86. load   your   own  custom  text  mouse  cursor   by   using   the
  87. SetMouseTextCursor function.
  88.  
  89.      The  TextMouse flag is used to identified whether the  mouse
  90. is  currently  in text or graphics mode.  Calling  the  MouseInit
  91. procedure  will cause the TextMouse flag to be set based  on  the
  92. value found in the BIOS CrtMode flag.
  93.  
  94.      if  you  are using a non-standard or extended  display  mode
  95. (graphic  or text), the mouse position translation  routines  may
  96. not  be  able to correctly translate the screen position  to  the
  97. virtual mouse position used by the mouse driver. You can  however
  98. override  the  mouse  position control  variables  after  calling
  99. InitMouse to perform your own translation.
  100.  
  101.  
  102.  
  103. Mouse Installation:
  104.  
  105.      The  Mouse program expects a MicroSoft or  compatible  mouse
  106. driver to be installed on the computer. All mouse operations  are
  107. performed through the mouse interrupt ($33). For more information
  108. on  using  the  mouse  interrupt refer  to  the  MicroSoft  Mouse
  109. Programmer's  Reference Guide available from MicroSoft or  though
  110. various computer book stores.
  111.  
  112.      If  the  mouse  driver  has not  been  installed,  then  the
  113. InitMouse procedure will set the MouseInstalled flag to false and
  114. most  mouse procedures will immediately terminate if called.  The
  115. basic  mouse functions will continue to operate however  if  your
  116. program   updates  the  MouseX  and  MouseY   mouse   positioning
  117. variables.  This allows keyboard mouse emulation if the mouse  is
  118. not available.
  119.  
  120.  
  121.  
  122. Starting out:
  123.  
  124.      The first thing to do to get the mouse going is to call  the
  125. InitMouse function near the beginning of your program before  you
  126. use the other mouse functions.
  127.  
  128.      The  InitMouse  function initailizes the mouse driver  to  a
  129. predefined state. You can call the InitMouse function at anytime,
  130. but you should realize that any previous state will be lost.
  131.  
  132.      Special note about Hercules:
  133.  
  134.           If  you  are using a Hercules display,  then  you  must
  135.      call the SetHercMouse function before calling the  InitMouse
  136.      function.  This is because the mouse driver must know  which
  137.      display  page and mode of the Hercules card you  are  using.
  138.      Also be sure to call the SetHercMouse function with a -1  to
  139.      return  it to text mode when you switch back to  text  mode.
  140.      An  exit  procedure has been provided in  Mouse  which  will
  141.      properly restore the function when you exit your program.
  142.  
  143.           The  reason  for  this special  handling  is  that  the
  144.      hercules  card  does not provide any way for the  system  to
  145.      know  if  it  is in text mode or graphics mode,  and  if  in
  146.      graphics  mode  which  page  is  selected.  As  such,   this
  147.      information  must  be  maintain by  the  user  program.  The
  148.      MicroSoft  mouse  driver uses the CrtMode variable  to  find
  149.      this  information  and leaves it up to the user  program  to
  150.      properly set the variable for desired operation.
  151.  
  152.  
  153.  
  154.  
  155. Showing the Mouse:
  156.  
  157.      Once you have the mouse initialized, You can make it  appear
  158. on the screen by calling the ShowMouse function.
  159.  
  160.      If the mouse was previously hidden, you must call  ShowMouse
  161. the  same  number of times that you called HideMouse to  get  the
  162. mouse to appear.
  163.  
  164.  
  165.  
  166. Hiding the Mouse:
  167.  
  168.      To  hide the mouse cursor you call the  HideMouse  function.
  169. You can call the HideMouse function multiple times. If the  mouse
  170. is currently visible it will be immediately hidden. If the  mouse
  171. cursor is not visible then a counter is decremented. To make  the
  172. mouse  visible again you must call ShowMouse the same number  (or
  173. more) times as you called HideMouse.
  174.  
  175.      Remember that InitMouse will always restore the mouse to the
  176. first  hidden level requiring only a single call to ShowMouse  to
  177. make the mouse cursor visible.
  178.  
  179.      Hiding the mouse does not disable the mouse, it only  causes
  180. the  mouse  cursor to not be displayed. All mouse  functions  are
  181. still fully operational. If the mouse is moved the mouse position
  182. will be updated even if the